TES4 Plugin Utility - Version 11.0
----------------------------------

This utility works with The Elder Scrolls: Oblivion plugin files (*.esp).  It will merge two or more plugins into a single plugin.  It will also convert a plugin file to a master file or a master file to a plugin file.  Selected plugin records can be displayed or copied to another plugin.

To install this utility, place the TES4Plugin.jar and the TES4Plugin-Silence.mp3 files into a directory of your choice.  To run the utility, create a program shortcut and specify "javaw -Xmx1024m -jar <install-directory>\TES4Plugin.jar" as the program to run where <install-directory> should be replaced with the directory where you extracted the jar file.  I have included a sample program shortcut in the zip file that specifies \Tmp as the install directory.  The -Xmx1024m specifies the maximum heap size in megabytes (the example specifies a heap of 1024 MB).  You can increase the size if you run out of space merging very large plugins.  Note that Windows will start swapping if the Java heap size exceeds the amount of available storage and this will significantly impact performance.

The Sun Java 1.5 runtime is required.  You can download JRE 1.5 from http://java.com/download/index.jsp.  If you are unsure what version of Java is installed on your system, open a command prompt window and enter "java -version".

Form ID and Editor ID conflicts are resolved by assigning new values.  For this reason, an existing save game may be invalidated if a new merged plugin file is created and a conflict exists that did not exist in an earlier merged plugin file.  The Form ID and Editor ID will not be changed if there are no conflicts with the existing values.

IMPORTANT NOTE: The TES4 Plugin Utility does not contain support for processing scripts.  If an Editor ID conflict occurs and you choose to rename the Editor ID, then you must check the scripts in the merged plugin and manually change the Editor ID from the old value to the new value.  The compiled scripts will work properly after the merge without any changes but the scripts will fail if they are recompiled without first updating the Editor ID values in the script source.

If two plugins modify the same record in a master file, the conflict is resolved by selecting those subrecords that are not the same as the corresponding master subrecords.  If both plugins modify the same subrecord, the subrecord from the first plugin or the second plugin will be used depending on which option was selected in the merge dialog.  Lists are handled by adding unique list items from the second plugin to the list from the first plugin.

Discussion of this TES4 utility is on the Bethesda Elder Scrolls Construction Set forum (http://www.elderscrolls.com/forums/).

ScripterRon


=========================================================================
=========================================================================


Available functions:


Convert to Master
-----------------

This function will convert a plugin file (*.esp) to a master file (*.esm).  The plugin file will not be deleted.  The output file will be overwritten if it exists.


Convert to Plugin
-----------------

This function will convert a master file (*.esm) to a plugin file (*.esp).  The master file will not be deleted.  The output file will be overwritten if it exists.


Display/Copy
------------

This function will display the records in a plugin.  

The "Ignore" flag can be set or reset to cause a record to be ignored when saving the plugin.  The record is physically removed from the plugin when the plugin is saved.  The "Ignore" flag for all records in a group will be toggled when a group is selected.  An attempt to set the "Ignore" flag for a subrecord will be ignored since subrecords do not have an "Ignore" flag.  

Records can be copied to a clipboard plugin called "TES4Plugin Clipboard.esp".  An existing clipboard plugin will be overwritten each time the clipboard is saved.  The clipboard plugin can be merged with another plugin or loaded by the Construction Set.  Any records referenced by the copied records will also be copied to the clipboard plugin.

The "Copy" and "Toggle Ignore" buttons work on the selected rows in the plugin tree display.  Multiple records can be selected using the normal Windows conventions.  Hold down the shift key to select all rows between the previous selection and the new row.  Hold down the ctrl key to add just the new row to the selection.


Edit Description
----------------

This function will edit the plugin creator and summary fields.


Generate Responses
------------------

This function will create response voice files for each dialog entry in the plugin.  The TES4Plugin-Silence.mp3 file is copied to the correct file names.  If the dialog uses the GetIsID function, a single file will be created based on the NPC race and gender.  If the dialog uses the GetIsRace function, two files (male and female) will be created based on the specified race.  Otherwise, two files (male and female) will be created for each playable race.


Merge Plugins
-------------

This function will merge two or more plugin files and create a new merged plugin file.  The output file will be overwritten if it exists.  The files will be merged in the order specified by the assigned priority values.  Priority 1 files will be merged before priority 2 files, priority 2 files will be merged before priority 3 files, etc.  Files with the same priority will be merged based on the file modification timestamps.  A file will not be merged if it has not been assigned a priority or if the priority value is not valid (priority values must be greater than zero).  Specify priority values by clicking on a row in the table and then typing in the desired number.

If you check the 'Delete last master record conflict' box, the second conflicting record will be removed from the merged file.  Otherwise, the first conflicting record will be removed.  Two records conflict if they both modify the same object in the master file.

If you check the 'Edit master leveled list conflicts' box, leveled list conflicts will be displayed and you will be able to manually merge the leveled list items.  Items can be copied from the plugin leveled list to the merged leveled list, items can be deleted from the merged leveled list, and the level and count values for items in the merged leveled list can be changed.  If this box is not checked, leveled list conflicts will be resolved by adding the unique entries from the second leveled list to the first leveled list (an entry is considered to be a duplicate of an existing entry if it has the same level number and item form ID).


Merge to Master
---------------

This function will merge a plugin file into an existing master file.  Items in the master file which are modified by the plugin will be replaced by the plugin definitions.  This allows master changes to be tested first in a plugin before committing the changes to the master.


Set Directory
-------------

This function set the directory containing the plugin files.  This is usually <Oblivion-install-directory>\Oblivion\Data but can be set to any directory.  The directory must already exist.


=========================================================================
=========================================================================


Record merge rules for master object conflicts
----------------------------------------------

ACTI - Activator

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


ALCH - Potion

The initial effects merged list contains all of the effects from the first occurrence of the potion in a plugin.  Unique effects from subsequents occurrences of the potion are then added to the merged list.  An effect is unique if it has a different effect name/subtype.  For a script effect, the effect is unique if it uses a different script.

The potion value will be set to the highest value encountered.  Auto-calculate will be turned off if it is off for any occurrence of the potion in a plugin.


AMMO - Ammunition

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


ANIO - Animated object

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


APPA - Apparatus

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


ARMO - Armor

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


BOOK - Book

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


BSGN - Birthsign

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.

The initial merged spell list contains all of the spells from the first occurrence of the birthsign in a plugin.  Unique spells from subsequent plugins are then added to the merged list.


CELL - Cell

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


CLAS - Class

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


CLOT - Clothing

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


CLMT - Climate

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


CONT - Container

Attribute subrecords are merge on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.

The initial merged container contains all of the items from the first occurrence of the container in a plugin.  Unique items from subsequent containers are then added to the merged container.


CREA - Creature

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.

The initial faction list contains all of the factions from the first occurrence of the creature in a plugin.  Unique factions from subsequent plugins are then added to the merged list.

The initial inventory list contains all of the items from the first occurrence of the creature in a plugin.  Unique items from subsequent plugins are then added to the merged list.

The initial merged spell list contains all of the spells from the first occurrence of the creature in a plugin.  Unique spells from subsequent plugins are then added to the merged list.

The initial merged package list contains all of the AI packages from the first occurrence of the creature in a plugin.  Unique packages from subsequent plugins are then added to the merged list.


CSTY - Combat style

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


DIAL - Dialog

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


DOOR - Door

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


EFSH - Effect shaders

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


ENCH - Enchantment

The initial effects merged list contains all of the effects from the first occurrence of the enchantment in a plugin.  Unique effects from subsequents occurrences of the enchantment are then added to the merged list.  An effect is unique if it has a different effect name/subtype.  For a script effect, the effect is unique if it uses a different script.

The total charge and cost for the enchantment will be set to the highest values encountered.  Auto-calculate will be turned off if it is off for any occurrence of the enchantment in a plugin.


EYES - Eyes

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


FACT - Faction

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.

Faction ranks are merged as a single entity based on which plugin has a different number of ranks than the master.  If both plugins have a different number of ranks, then the faction ranks are chosen based on whether the first or the last conflict should be deleted.

The initial interfaction relations merged list contains all of the factions from the first occurrence of the faction in a plugin.  Unique interfaction relations from subsequent occurrences of the faction are then added to the merged list.


FLOR - Flora

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


FURN - Furniture

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


GRAS - Grass

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


GLOB - Global Variable

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


GMST - Game Setting

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be delete.


HAIR - Hair

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


IDLE - Idle animation

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


INGR - Ingredient

The initial effects merged list contains all of the effects from the first occurrence of the ingredient in a plugin.  Unique effects from subsequents occurrences of the ingredient are then added to the merged list.  An effect is unique if it has a different effect name/subtype.  For a script effect, the effect is unique if it uses a different script.

The ingredient value will be set to the highest value encountered.  Auto-calculate will be turned off if it is off for any occurrence of the ingredient in a plugin.


KEYM - Key

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


LIGH - Light

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


LSCR - Load screen

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


LVLC - Leveled Creature, LVLI - Leveled Item, LVSP - Leveled Spell

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.

The initial merged list contains all of the list items from the first occurrence of the leveled list in a plugin.  Unique list items from subsequent leveled lists are then added to the merged list.


LTEX - Land texture

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


MGEF - Magic effects

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


MISC - Miscellaneous item

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


NPC - Non-player character

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.

The initial faction list contains all of the factions from the first occurrence of the NPC in a plugin.  Unique factions from subsequent plugins are then added to the merged list.

The initial inventory list contains all of the items from the first occurrence of the NPC in a plugin.  Unique items from subsequent plugins are then added to the merged list.

The initial merged spell list contains all of the spells from the first occurrence of the NPC in a plugin.  Unique spells from subsequent plugins are then added to the merged list.

The initial merged package list contains all of the AI packages from the first occurrence of the NPC in a plugin.  Unique packages from subsequent plugins are then added to the merged list.


PACK - Package

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


QUST - Quest

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


RACE - Race

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.

Racial abilities and reactions are merged by adding unique entries from each plugin to the current merged list.

Face and body meshes/textures are chosen based on which ones are different from the corresponding master value.  If both plugins are different from the master, then the mesh/texture is chosen based on whether the first or the last conflict should be deleted.


REGN - Region

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


SBSP - Subspace

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


SCPT - Script

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


SGST - Sigil stone

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


SKIL - Skill

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


SLGM - Soul gem

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


SOUN - Sound

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


SPEL - Spell

The initial effects merged list contains all of the effects from the first occurrence of the spell in a plugin.  Unique effects from subsequents occurrences of the spell are then added to the merged list.  An effect is unique if it has a different effect name/subtype.  For a script effect, the effect is unique if it uses a different script.

The total cost and skill level for the spell will be set to the highest values encountered.  Auto-calculate will be turned off if it is off for any occurrence of the spell in a plugin.


STAT - Static

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


TREE - Tree

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


WATR - Water

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


WEAP - Weapon

Attribute subrecords are merged on a one-by-one basis.  A plugin subrecord is chosen if it is not the same as the corresponding subrecord in the master.  If both plugin subrecords are different from the master subrecord, then the subrecord is chosen based on whether the first or the last conflict should be deleted.


WRLD - World space

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


WTHR - Weather

The entire record is merged.  A plugin record is chosen if it is not the same as the corresponding record in the master.  If both plugin records are different from the master record, then the record is chosen based on whether the first or the last conflict should be deleted.


=========================================================================
=========================================================================


Version 1:
----------

Initial release.


Version 2:
----------

Top-level records marked as 'Ignore' will not be copied to the merged plugin.  Records in sub-groups will still be copied even if marked as 'Ignore' until I know more about what happens when you omit records found in a sub-group.

Compressed records are expanded as needed instead of expanding all records when loading the plugin.  This should significantly reduce the storage requirements when merging large plugins.

WRLD and CELL records in a master can be modified by multiple plugins.  An error will still be posted if any other record type is modified by more than one plugin.  Research is continuing to determine what can safely be modified without breaking the merged plugin.


Version 3:
----------

Add the capability to convert a master file to a plugin file.

Add the capability to edit the plugin description.

Create the application preferences data directory if it doesn't exist.

The XCHG subrecord is now recognized.

References in additional subrecords are now adjusted when merging plugins.

The CS ignores underscores in an Editor ID, so conflicts will now be resolved by appending 'X' to the Editor ID.


Version 4:
----------

Add the Display Records function.

All ignored records are deleted during a merge.

Leveled lists (creature, item, spell) are now merged.


Version 5:
----------

Add the capability to display the complete subrecord data in a popup window.

Conditions are now processed properly in quest (QUST), package (PACK) and dialog (INFO) records.

Top-level groups now have descriptive names instead of the 4-character record type.


Version 6:
----------

Deleted records are indicated in the record display tree view.

Eyes (ENAM) and Hair (HNAM) subrecords are now processed properly for Races.

Conflicts will be removed from the merged file.

Duplicate items will be removed from the merged file.

The plugin merge list is now sorted by the last modified date.

The Set Directory function now uses a file chooser dialog.

Leveled list conflicts can be edited during the merge.


Version 7:
----------

Both references in the race voice override subrecord (VNAM) will be updated during a merge.

Add the capability to generate silent dialog response files.

Add the capability to merge a plugin file into a master file.

Merge the associated voice files when merging plugins.

The merge order is now specified explicitly by the user instead of being determined by the file modification dates.

Change the Display Records function to display both master files and plugin files.

WRLD, CELL and DIAL subgroups will be merged instead of being duplicated.


Version 8:
----------

Fix problem with form ID conflicts after a master record conflict.

Duplicate references not removed when merging subgroup.

Group label not updated when the label is a form ID (WRLD/CELL/DIAL).

Update references in XTEL and XLOC subrecords.

Replace NL with CRLF in plugin summary.


Version 9:
----------

Use a case-insensitive compare when checking for Editor ID conflicts.

When displaying a plugin, sort the records for a top-level group based on the Editor ID.

Correctly handle ENAM subrecord for SKIL record.

Correctly handle MGEF record.

Correctly handle SCIT subrecord for ENCH and SPEL records.

Correctly handle adding a tail to an existing race.

Add spill file support.

Add shortcut keys to the display dialog.

Toggle the "Ignore" flag for all records in a group when "Toggle Ignore" is selected for a group.

Accept Version 1.0 plugin files.  New plugin files are still created as Version 0.8.

Don't save ignored records and empty groups.


Version 10:
-----------

Add subrecord merge support.

Copy records referenced by the selected records for the Display/Copy function.

Don't build the subrecord nodes for the Display/Copy function until they are needed.

Correctly handle the same CELL record in different groups.

Correctly handle XCLR subrecord for CELL records.

Allow a plugin to rename an object in a master file.


Version 11:
-----------

Allow any record or group to be copied.

Update GetDistance function references.

Handle escape sequences (%xx) in file URL paths.
